/*********************************************************
   Copyright: (C) 2008-2010 by Steven Schveighoffer.
              All rights reserved

   License: Boost Software License version 1.0

   Permission is hereby granted, free of charge, to any person or organization
   obtaining a copy of the software and accompanying documentation covered by
   this license (the "Software") to use, reproduce, display, distribute,
   execute, and transmit the Software, and to prepare derivative works of the
   Software, and to permit third-parties to whom the Software is furnished to
   do so, all subject to the following:

   The copyright notices in the Software and this entire statement, including
   the above license grant, this restriction and the following disclaimer, must
   be included in all copies of the Software, in whole or in part, and all
   derivative works of the Software, unless such copies or derivative works are
   solely in the form of machine-executable object code generated by a source
   language processor.

   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
   FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
   SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
   FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
   DEALINGS IN THE SOFTWARE.

**********************************************************/
module dcollections.model.Addable;

public import dcollections.model.Iterator;

private import std.range;

/**
 *  Define an interface for collections that are able to add values.
 *
 *  Note, this used to contain versions of add that also output whether
 *  elements were added, but this has been replaced by
 *  dcollecitons.util.lengthChain.  The only thing missing is if you *only*
 *  have an Addable interface, you cannot use lengthChain.  But this situation
 *  of needing to know if an element is added and only having an Addable
 *  interface is rather rare.
 */
interface Addable(V)
{
    /**
     * Add one or more elements.  Takes O(M * lgN) time or better, where M is
     * the number of elements in elems, and N is the number of elements
     * currently in the collection.
     *
     * returns this.
     */
    Addable add(V[] elems...);

    /**
     * add all values retrieved from the collection using the iterator's
     * opApply.  Returns this.
     */
    Addable add(Iterator!(V) it);

    /**
     * add all the values from a range.  Returns this.
     *
     * TODO: change name to add
     */
    Addable addRange(R)(R range) if (isInputRange!R && is(ElementType!R == V))
    {
        foreach(v; range)
            add(v);
        return this;
    }
}
